.\" -*- nroff -*-
.\" Copyright © 2009-2010 INRIA.  All rights reserved.
.\" Copyright © 2010 Université of Bordeaux
.\" Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-BIND "1" "#HWLOC_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME
hwloc-bind \- Launch a command that is bound to specific processors
and/or memory.
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.B hwloc-bind
[\fIoptions\fR] \fI<location1> [<location2> [...] ] [--] <command> \fR...
.
.\" **************************
.\"    Options Section
.\" **************************
.SH OPTIONS
.
See below for a description of valid <location> formats.
.TP 10
\fB\-\-cpubind\fR
Use following arguments for CPU binding (default).
.TP
\fB\-\-membind\fR
Use following arguments for memory binding.
.TP
\fB\-\-mempolicy\fR <policy>
Change the memory binding policy.
The available policies are default, firsttouch, bind, interleave
replicate and nexttouch.
If a binding set is given, the default policy is bind.
.TP
\fB\-\-get\fR
Report the current bindings.
When combined with \fB\-\-membind\fR, report the memory binding
instead of CPU binding.
.TP
\fB\-\-get-last-cpu-location\fR
Report the last processors where the process ran.
Note that the result may already be outdated when reported since
the operating system may move the process to other processors
at any time according to the binding.
This option cannot be combined with \fB\-\-membind\fR.
.TP
\fB\-\-single\fR
Bind on a single CPU to prevent migration.
.TP
\fB\-\-strict\fR
Require strict binding.
.TP
\fB\-\-get\fR
Retrieve the current process binding
.TP
\fB\-\-pid\fR <pid>
Operate on pid <pid>
.TP
\fB\-p\fR \fB\-\-physical\fR
take OS/physical indexes instead of logical indexes
.TP
\fB\-l\fR \fB\-\-logical\fR
take logical indexes instead of physical/OS indexes (default)
.TP
\fB\-\-taskset\fR
Manipulate CPU set strings in the format recognized by the taskset command-line
program instead of hwloc-specific CPU set string format.
.TP
\fB\-v\fR
Verbose output.
.TP
\fB\-\-version\fR
Report version and exit.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH DESCRIPTION
.
hwloc-bind execs an executable (with optional command line arguments)
that is bound to the specified location (or list of locations).  Upon
successful execution, hwloc-bind simply sets bindings and then execs
the executable over itself.
.
.PP
.B NOTE:
It is highly recommended that you read the hwloc(7) overview page
before reading this man page.  Most of the concepts described in
hwloc(7) directly apply to the hwloc-bind utility.
.
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH EXAMPLES
.PP
hwloc-bind's operation is best described through several examples.
More details about how locations are specified on the hwloc-bind
command line are described in hwloc(7).
.
.PP
To run the echo command on the first logical processor of the second
socket:

    hwloc-bind socket:1.pu:0 -- echo hello

which is exactly equivalent to

    hwloc-bind socket:1.pu:0 echo hello

To bind the "echo" command to the first core of the second socket and
the second core of the first socket:

    hwloc-bind socket:1.core:0 socket:0.core:1 echo hello

Note that binding the "echo" command to multiple processors is
probably meaningless (because "echo" is likely implemented as a
single-threaded application); these examples just serve to show what
hwloc-bind can do.
.
.PP
To run on the first three sockets on the second and third nodes:

    hwloc-bind node:1-2.socket:0:3 echo hello

which is also equivalent to:

    hwloc-bind node:1-2.socket:0-2 echo hello

Note that if you attempt to bind to objects that do not exist,
hwloc-bind will not warn unless 
.I -v 
was specified.

To run on processor with physical index 2 in socket with physical index 1:

    hwloc-bind --physical socket:1.core:2 echo hello

To run on odd cores within even sockets:

    hwloc-bind socket:even.core:odd echo hello

To run on the first socket, except on its second and fifth cores:

    hwloc-bind socket:0 ~socket:0.core:1 ~socket:0.core:4 echo hello

To run anywhere except on the first socket:

    hwloc-bind all ~socket:0 echo hello

To bind memory on second memory node and run on first node (when supported by the OS):

    hwloc-bind --cpubind node:1 --membind node:0 echo hello

The --get option can report current bindings.  This example shows
nesting hwloc-bind invocations to set a binding and then report it:

    hwloc-bind node:1.socket:2 hwloc-bind --get

On one of the hwloc developer's machines, this example
.
reports "0x00004444,0x44000000".  The mask reported on your machine
may be different.
.
.PP
Locations may also be specified as a hex bit mask (typically generated
by hwloc-calc).  For example:

    hwloc-bind 0x00004444,0x44000000 echo hello
    hwloc-bind `hwloc-calc node:1.socket:2` echo hello

Memory binding may also be reported:

    hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind --get --membind

This returns a string describing the memory binding, such as "0x000000f0
(interleave)".  Note that if the system does not contain any NUMA
nodes, the reported string will indicate that the process is bound to
the entire system memory (e.g., "0xf...f").
.
.\" **************************
.\"    Return value section
.\" **************************
.SH RETURN VALUE
Upon successful execution, hwloc-bind execs the command over itself.
The return value is therefore whatever the return value of the command
is.
.
.PP
hwloc-bind will return nonzero if any kind of error occurs, such as
(but not limited to): failure to parse the command line, failure to
retrieve process bindings, or lack of a command to execute.
.
.\" **************************
.\"    See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
.sp
